home *** CD-ROM | disk | FTP | other *** search
/ Libris Britannia 4 / science library(b).zip / science library(b) / PROGRAMM / CC_C / 1116.ZIP / TOOLKIT.ARC / TUTOR.DOC < prev    next >
Text File  |  1979-12-31  |  14KB  |  283 lines
  1.  
  2.                             WHY USE SMALL C ?
  3.  
  4.           SmallC:PC,  adapted for  use  in MS-DOS  by Caprock  Systems,
  5.      Inc.,  has  been  circulated  by public  domain  distributors  for
  6.      several years now.   This nice subset compiler,  complete with its
  7.      own source code  (CPC.*) and linkable run-time  module  (CPCLIB.*)
  8.      is  usually  found  buried  among a  collection  of  uncompiled  C
  9.      programs that will  not run under Small C.   Some attention should
  10.      be given to this C compiler, because  it works, it is easy to use,
  11.      and it can run on not-so-PC-compatibles.
  12.           Recalling my own  first encounter with Small  C, and comments
  13.      from friends  who had  at one  time or another  sought to  whip up
  14.      something  in  Small C,  I  suspect  that  many would-be  Small  C
  15.      programmers never  get past  the CPC compile  phase.  But,  let me
  16.      assure you, the compiler does work.  It also locates and describes
  17.      program  errors very  clearly at  compile time  on your  CRT.  The
  18.      following two tips may be all you need to get up and running.
  19.           In  contemporary zeitgeist,  printf("Hello") is  the function
  20.      call of "the minimal C program".  Unfortunately, printf() does not
  21.      exist in CPCLIB.*.   If puts("Hello") is used in Small  C there is
  22.      no problem, and this is  standard syntax, supported by the popular
  23.      C compilers such  as Lattice C.  So, this is  "the minimal Small C
  24.      program":
  25.                  /* the minimal Small C program */
  26.                  main()
  27.                        {
  28.                         puts("Hello");
  29.                        }
  30.  
  31.           Another rudimentary  pitfall is  in the non-standard  Small C
  32.      syntax used  to include header files.  The usual syntax would look
  33.      like this:  #include<stdio.h>   or like:  #include"stdio.h"
  34.           Small c syntax is different, since the prevailing incarnation
  35.      of  the compiler  does not  do  enough parsing  of the  '#include'
  36.      instruction to accomodate  the standard C syntax.   So, to include
  37.      the  header  file  MYFILE.H,  use #include  MYFILE.H  or  #include
  38.      B:MYFILE.H .  The header  file is  not pre-compiled,  but it  must
  39.      exist  and  be accessible  during  CPC  compilation.  As with your
  40.      Small C program source code, your Small C header files are simple,
  41.      flat ASCII files created with any text editor you like. Here is an
  42.      example:
  43.                  /* this is a Small C header file named NOISE.H */
  44.                  buzzer()
  45.                          {
  46.                           putchar(7);
  47.                          }
  48.  
  49.           Here is an example Small C program that includes NOISE.H:
  50.  
  51.                  /* this program sounds the console bell */
  52.                  #include noise.h
  53.                  main()
  54.                        {
  55.                         buzzer();
  56.                        }
  57.  
  58.  
  59.                SO WHAT'S THE ADVANTAGE TO USING SMALL C ?
  60.  
  61.           On disk, the resolved run-time module is just under 4K bytes,
  62.      as opposed  to 11K bytes in  Pascal or 18K to 20K for the BASIC,
  63.      COBOL, and ForTran compiler packages you are likely to find.
  64.           This is  a significant difference, and the effects are often
  65.      cumulative for those of us who write short batch utility programs,
  66.      and it is an expedient  alternative to programming in assembler at
  67.      a minimized cost in disk space.
  68.           Also, Small-c:PC is still probably the easiest C language
  69.      implementation to set up and use, given a little guidance.
  70.  
  71.                    SO WHAT DO I WANT THIS DISK FOR ?
  72.  
  73.           Commercial full  C compilers  are usually packaged  with many
  74.      ready-to-use header files.  Unfortunately, Small C cannot make use
  75.      of these files,  because the STRUCT and UNION  constructs have not
  76.      been implemented in Small C, and most of the standard header files,
  77.      such as STDIO.H, usually use these constructs.
  78.           Aside from this Small-c:PC tutorial, this disk contains the
  79.      header files STDIO.H and GETINT.H.  These two header files, and the
  80.      other header files on this disk, make Small C practical and useful.
  81.  
  82.          DO I NEED TO BE AN ASSEMBLY LANGUAGE EXPERT TO USE SMALL C ?
  83.  
  84.           NO.  A study of the header files will reveal that I used in-line
  85.      assembler in only one header, PUTRCHAR.H, for the putrchar() function.
  86.      Also, since STDIO.H and GETINT.H are now available to you, your Small
  87.      c programs will not have to be shrouded in uncertainties or various
  88.      and rambling I/O experimentations.
  89.  
  90.       WHAT IS THE SEQUENCE OF EVENTS THAT RESULTS IN A FINISHED PROGRAM ?
  91.  
  92.          1. Use a text editor to write your Small C program.
  93.               A. Convention would be to use *.C as the filename extension.
  94.          2. Use CPC.EXE, the public domain Small-c:PC compiler.
  95.               A. Convention here would be to use *.ASM as the filename,
  96.                  since CPC.EXE creates a file that is the assembly
  97.                  language equivalent of your Small C program.
  98.          3. Use MASM.EXE, the Microsoft Macro Assembler, or any public
  99.             domain assembler that can be used to create *.EXE files.
  100.               A. The file that you assemble is the *.ASM file created by
  101.                  CPC.EXE in step 2.
  102.               B. Convention here would be to name the object file created
  103.                  by MASM.EXE using the filename extension *.OBJ
  104.          4. Use LINK.EXE, the Microsoft linker that is found on your
  105.             original MS-DOS or PC-DOS or TRS-DOS system disk.
  106.               A. LINK.EXE goes like this:
  107.                                           A>LINK
  108.                                             OBJECT MODULES[.OBJ]: MYPROG.OBJ
  109.                                             RUN FILE [MYPROG.EXE]: MYPROG.EXE
  110.                                             MAP FILE [.MAP]: <cr>
  111.                                             LIBRARIES [.LIB]: CPCLIB.LIB
  112.               B. This creates MYPROG.EXE
  113.          5. A>MYPROG    (This executes your program directly in MS-DOS)
  114.  
  115.  
  116.      Below is a directory listing the documentation files on this disk:
  117.  
  118.      DECOM    DOC   Documentation and source code for DECOM.COM
  119.      HEXPRINT DOC   Documentation for HEXPRINT.C
  120.      MLBAT    DOC   Documentation for ML1.BAT ML2.BAT and ML3.BAT
  121.      SOUNDEX  DOC   Documentation for SOUNDEX.C (a simple demo program)
  122.      README   DOC   Quick reference of functions in each header file
  123.      TUTOR    DOC   This Small C tutorial.
  124.             6 File(s)
  125.  
  126.      ---------------------------------------------------------------------
  127.                           ADVANCED SMALL C TOPICS:
  128.  
  129.      Below is the multi-segment envelope into which Small-c:PC packages
  130.      all programs. The high-level Small-c source code for the tiny example
  131.      program below has been rewritten in assembly code by the CPC.EXE
  132.      compiler.  The CPC compilation simply creates a new additional file
  133.      that is the assembly language source code equivalent of the Small-c:PC
  134.      program source code.
  135.  
  136.           main()       \
  137.           {             \_____ SHELL.C  created by me as Small-c:PC
  138.           }             /               program source code.
  139.                        /                (Created via a text editor.)
  140.  
  141.      ;* * *  Small-C:PC  V1.1  * * *         \
  142.      ;PC-DOS Version N: June, 1982            \
  143.      ;By Ron Cain, Modified by CAPROCK SYSTEMS \
  144.      ;                                          \
  145.      CSEG SEGMENT BYTE PUBLIC 'code'             \
  146.       ASSUME CS:CSEG,SS:STACK                     \
  147.      ;main()                                       \
  148.       PUBLIC QZMAIN                                 \
  149.      QZMAIN:                                         \
  150.      ;{                                               \____ SHELL.ASM
  151.      ;}                                               /     created by
  152.       RET                                            /       CPC.EXE
  153.      CSEG ENDS                                      /
  154.      DUMMY SEGMENT BYTE STACK 'dummy'              /
  155.      DUMMY ENDS                                   /
  156.      STACK SEGMENT BYTE PUBLIC 'stack'           /
  157.      STACK ENDS                                 /
  158.      ; --- End of Compilation ---              /
  159.       END                                     /
  160.  
  161.  
  162.      DECOM.COM can be used to reduce the size of Small-c *.ASM files.
  163.      It strips away assembler code comment lines.  The code listed below
  164.      is the Small-c multi-segment envelope, in perhaps more readable form.
  165.      As you can see, DECOM.COM was used to strip away the comment lines.
  166.      DECOM.COM will probably be useful only if you are still limited to
  167.      single-sided floppy disks or if you are inclined toward including
  168.      header files rather than linking object modules.
  169.  
  170.      CSEG SEGMENT BYTE PUBLIC 'code'  \
  171.       ASSUME CS:CSEG,SS:STACK          \
  172.       PUBLIC QZMAIN                     \
  173.      QZMAIN:                             \
  174.       RET                                 \_______  SHELL.ASM after DECOM
  175.      CSEG ENDS                            /
  176.      DUMMY SEGMENT BYTE STACK 'dummy'    /
  177.      DUMMY ENDS                         /
  178.      STACK SEGMENT BYTE PUBLIC 'stack' /
  179.      STACK ENDS                       /
  180.       END                            /
  181.  
  182.  
  183.      An important point to remember here is that the Small-c:PC envelope is a
  184.      multi-segment package.  This means that you can not use EXE2BIN in MS-DOS
  185.      to convert your finished *.EXE program files into *.COM files. It also means
  186.      that your Small-c:PC programs are not necessarily limited to a small model
  187.      (which would be 64 Kbytes in MS-DOS).
  188.  
  189.      A side note also worth mentioning here is that the CPC.EXE compiler will
  190.      compile your header files by themselves, so that you can transform them
  191.      into *.ASM files, and then into *.OBJ files using MASM.  The fact that
  192.      main() is missing does not produce a compile error.  This practice of
  193.      turning your header routines into linkable *.OBJ modules will make
  194.      program development in Small-c:PC a pleasure, because it greatly reduces
  195.      CPC compile time as well as MASM assembly time, and the increase in LINK
  196.      time is hardly noticeable.  This also conserves disk space which would
  197.      otherwise be quickly swallowed up in *.ASM  files.  The run-time file
  198.      CPCLIB.OBJ is a linkable *.OBJ file (sometimes CPCLIB.ASM and CPCLIB.OBJ
  199.      have been distributed in the public domain and sometimes CPCLIB.LIB is
  200.      distributed).  See ML2.BAT and ML3.BAT and HELLO3.C for linkage examples.
  201.  
  202.      CPCLIB.* is the run-time module.  You must link either CPCLIB.LIB or
  203.      CPCLIB.OBJ to your program object file in order to produce an *.EXE file.
  204.      If you do not link CPCLIB.* then a linkage error will occur, and you will
  205.      simply have to try LINK again.
  206.  
  207.  
  208.      Below is a directory of the Small-c:PC example program source code files.
  209.      Any of the new functions used in a program are listed on the right.
  210.  
  211.      BARS     C   241   hbar() vbar() cls550()
  212.      BLANKING C   783   blank() nochars() cursor() cls550()
  213.      CLS550   C   138   cls550()
  214.      CTYPE    C   610   toupper() tolower()
  215.      CULATOR  C   131   culator()
  216.      CURSOR   C   242   cursor()
  217.      GETNUM   C  1219   getint() getval() printf() cls550()
  218.      HELLO1   C    73   uses CPCLIB.* functions only
  219.      HELLO2   C   100   printf()
  220.      HELLO3   C   422   printf()
  221.      HEXPRINT C   342   hexprint()
  222.      MODE     C   547   findmode() color() vblock()
  223.      NOT      C   468   not() printf()
  224.      PUTRCHAR C   528   putrchar() putrs()
  225.      SOUNDEX  C  3836   uses CPCLIB.* functions only
  226.      STATS    C  1435   min() max() size() occ() span() lactd() sactd()
  227.                         printf() cls550()
  228.      STRING   C   461   strlen() strpos() printf()
  229.      WINDOW   C   262   window()
  230.      _FILES   C  1269   fprintf()
  231.      _STDIO   C   523   printf() prnstr() prnchar()
  232.            20 File(s)
  233.  
  234.  
  235.      Below is a directory of the Small-c:PC header file source code files.
  236.      All functions in any particular *.H file are listed on the right.
  237.      Study of the source code in these header files will reveal that none
  238.      of the *.H files are dependent on functions found only in other *.H
  239.      files. -This means that you can include or link any or all of them.
  240.  
  241.      BARS     H   852   vbar() hbar()
  242.      BLANKING H  1565   blank() nochars()
  243.      CLS550   H   438   cls550()
  244.      CTYPE    H   707   toupper() tolower()
  245.      CULATOR  H  6547   culator()
  246.      CURSOR   H   337   cursor()
  247.      GETINT   H  8170   getint() getval()
  248.      MODE     H  1122   setmode() findmode() color() vblock()
  249.      NOT      H  1055   not()
  250.      PUTRCHAR H  1230   putrchar() putrs()
  251.      STATS    H  5204   min() max() size() lactd() sactd() occ() span()
  252.      STDIO    H  8848   printf() prnchar() prnstr() prnf()
  253.      STRING   H  2623   strlen() strpos() charpos()
  254.      WINDOW   H   600   window()
  255.      _FILES   H  8343   hexprint() fprintf()
  256.            15 File(s)
  257.  
  258.      If you have followed me through to this point with no problem then you
  259.      are an experienced PC programmer, and you are ready to take note that
  260.      the video functions are currently not doing any paging.  All video
  261.      control uses the BIOS interrupt 10h in page 0.  This was done to simplify
  262.      and shorten the list of values sent to the new functions.  And, since I
  263.      have provided the functions in source code form, a programmer familiar
  264.      with BIOS interrupt 10h can easily implement the changes to allow for
  265.      video paging on color screens, if the need arises.
  266.  
  267.  
  268.      THIS DISK IS INTENDED FOR PUBLIC DOMAIN DISTRIBUTION.  NO EXPRESS
  269.      OR IMPLIED GUARANTEE AS TO THE FUNCTIONALITY OF ANY SOFTWARE ON
  270.      DISK FOR ANY SPECIFIC PURPOSE IS INTENDED.  I HAVE SUBMITTED THIS
  271.      DISK TO PUBLIC DOMAIN DISTRIBUTION TO PROMOTE THE USE OF SMALL-C,
  272.      IN THE HOPE THAT MORE SMALL-C HEADERS AND FUNCTIONS WILL BECOME
  273.      AVAILABLE TO ME IN THE PUBLIC DOMAIN FROM OTHER INTERESTED USERS.
  274.  
  275.                                Wayne Pearson
  276.                                RD2  Box 5533
  277.                                Montpelier, VT 05602
  278.  
  279.  
  280.  
  281.  
  282.  
  283.